Intent.requestConfirmation PRO#

Intent.requestConfirmation pauses script execution and asks the user to confirm an action through a system-managed confirmation UI. The confirmation interface consists of:

• A SnippetIntent UI (provided by you)
• Optional dialog text (system-generated or developer-defined)

Behavior:

• If the user confirms, the script continues (Promise resolves).
• If the user cancels, the script terminates immediately.
• The UI is fully managed by the system.
• The presented UI is defined by the provided SnippetIntent’s perform() return.

This API is only available on iOS 26 or later.

API Definition#

1Intent.requestConfirmation(
2  actionName: ConfirmationActionName,
3  snippetIntent: AppIntent<any, VirtualNode, AppIntentProtocol.SnippetIntent>,
4  options?: {
5    dialog?: Dialog;
6    showDialogAsPrompt?: boolean;
7  }
8): Promise<void>

Parameter Details#

actionName: ConfirmationActionName#

A semantic keyword describing the type of action being confirmed. Apple uses this value to generate natural language around the confirmation UI.

Accepted values include:

Examples:

• "set" → “Do you want to set…?”
• "buy" → “Do you want to buy…?”
• "toggle" → “Do you want to toggle…?”

Choosing the correct semantic verb improves the clarity of the user-facing dialog.

snippetIntent: SnippetIntent#

This must be an AppIntent registered with:

1protocol: AppIntentProtocol.SnippetIntent;

The UI displayed in the confirmation step comes from this SnippetIntent’s perform() return, which must be a TSX-based VirtualNode.

This is what the user sees and interacts with during confirmation.

options?: { dialog?: Dialog; showDialogAsPrompt?: boolean }#

dialog?: Dialog#

Optional text describing the confirmation request. Supports four formats:

1type Dialog =
2  | string
3  | { full: string; supporting: string }
4  | { full: string; supporting: string; systemImageName: string }
5  | { full: string; systemImageName: string };

Examples:

1"Are you sure you want to continue?";

More structured version:

1{
2  full: "Set this color?",
3  supporting: "This will update the theme color used across the app.",
4  systemImageName: "paintpalette"
5}

Use this to clearly explain what the user is confirming.

showDialogAsPrompt?: boolean#

• Default: true The system shows the dialog as a modal prompt.

• false The dialog may be integrated directly inside the Snippet card instead of a separate prompt.

Execution Flow#

When the script executes:

1await Intent.requestConfirmation(...)

The following occurs:

1. Script execution is paused.

2. The system displays:

   • The SnippetIntent UI
   • Optional dialog text

3. The user chooses:

   • Confirm → Promise resolves → script continues
   • Cancel → script stops immediately

4. The system handles UI presentation and dismissal automatically.

There is no need to manually manage the UI lifecycle.

Usage Scenarios#

Recommended for:

• Confirming important changes (colors, appearance, configurations)
• Confirming destructive or irreversible actions
• Steps requiring explicit user approval
• Initiating subflows requiring UI preview or choice (e.g., color picker, item selector)
• Sensitive operations (e.g., updating settings, performing actions with side effects)

Not recommended for:

• Actions that do not require user approval
• Simple background data processing

Complete Example#

Below is a full working example demonstrating how to request user confirmation using a SnippetIntent.

It assumes you have two SnippetIntent AppIntents:

• PickColorIntent — allows user to select a color
• ShowResultIntent — displays the final result

intent.tsx#

1import { Intent, Script } from "scripting";
2import { PickColorIntent, ShowResultIntent } from "./app_intents";
3
4async function runIntent() {
5  // Step 1: Ask the user to confirm the action via a Snippet UI
6  await Intent.requestConfirmation("set", PickColorIntent(), {
7    dialog: {
8      full: "Are you sure you want to set this color?",
9      supporting: "This will update the theme color used by your app.",
10      systemImageName: "paintpalette",
11    },
12  });
13
14  // Step 2: Read input from Shortcuts
15  const text =
16    Intent.shortcutParameter?.type === "text"
17      ? Intent.shortcutParameter.value
18      : "No text parameter from Shortcuts";
19
20  // Step 3: Return another SnippetIntent result
21  const snippet = Intent.snippetIntent({
22    snippetIntent: ShowResultIntent({ content: text }),
23  });
24
25  Script.exit(snippet);
26}
27
28runIntent();

Notes & Best Practices#

• Requires iOS 26+ — do not call this API on earlier versions.
• Always include a clear dialog message to improve user understanding.
• Use for actions that require explicit approval or confirmation.
• When possible, combine with SnippetIntent to provide a richer preview UI.
• Scripts terminate automatically when the user cancels; do not rely on cleanup code afterward.
• Avoid calling it unnecessarily; only use when confirmation is truly meaningful.